Skip to content

docs: update tools field examples to comma-separated format#134

Merged
sjnims merged 1 commit intomainfrom
docs/132-update-tools-field-format
Dec 11, 2025
Merged

docs: update tools field examples to comma-separated format#134
sjnims merged 1 commit intomainfrom
docs/132-update-tools-field-format

Conversation

@sjnims
Copy link
Copy Markdown
Owner

@sjnims sjnims commented Dec 11, 2025

Summary

Updates the agent-development skill documentation to use comma-separated format for the tools field instead of array format, aligning with official Claude Code documentation.

Problem

Fixes #132

The documentation examples showed array format (tools: ["Read", "Write"]) while official Claude Code docs use comma-separated format (tools: Read, Write). This inconsistency could confuse users creating agents.

Solution

Updated all tools field examples to use comma-separated format to match:

  • Official sub-agents.md documentation
  • Existing agents in this plugin (plugin-validator.md, skill-reviewer.md, agent-creator.md)

Alternatives Considered

  • Leave as array format: Rejected because it contradicts official documentation
  • Support both formats: Not applicable - this is documentation only, not code

Changes

  • SKILL.md:116 - Complete Format example
  • SKILL.md:228-231 - tools field format description and code block
  • SKILL.md:238-242 - Common tool sets section
  • SKILL.md:441 - Frontmatter Fields Summary table

Testing

  • Markdownlint passes
  • Changes are documentation-only (no functional impact)
  • Format matches official documentation

🤖 Generated with Claude Code

Update agent-development skill to use comma-separated format for tools field
instead of array format, matching official Claude Code documentation.

Changes:
- Line 116: Complete Format example
- Lines 228-231: tools field format description and example
- Lines 238-242: Common tool sets section
- Line 441: Frontmatter Fields Summary table

The actual agents in this plugin already use correct format; this aligns
documentation examples with official sub-agents.md reference.

Fixes #132

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Copy link
Copy Markdown

claude Bot commented Dec 11, 2025

Claude finished @sjnims's task in 1m 20s —— View job


PR Review: docs: update tools field examples to comma-separated format

Summary

Looks good - recommend merge

This is a clean documentation fix that resolves an important inconsistency. All changes are correct and align with official Claude Code documentation.


What's Good

1. Accuracy & Consistency

  • All 4 locations updated correctly (lines 116, 228-231, 238-242, 441)
  • Format now matches official sub-agents.md documentation
  • Consistent with existing agents in this plugin (agent-creator.md:44, plugin-validator.md:43, skill-reviewer.md:43)

2. Documentation Quality

3. Completeness
All relevant sections updated:

  • Complete Format example (line 116)
  • Field description and format specification (lines 228-231)
  • Common tool sets examples (lines 238-242)
  • Frontmatter Fields Summary table (line 441)

4. Improved Clarity
The change from tools: ["*"] to "Omit field entirely" for full access is more accurate - the array syntax was never correct for this field.


Technical Verification

Existing agents in this plugin already use correct format:

# agent-creator.md:44
tools: Write, Read, Glob

# plugin-validator.md:43
tools: Read, Grep, Glob, Bash

# skill-reviewer.md:43
tools: Read, Grep, Glob

All 4 documentation updates:

  1. Line 116: tools: ["Read", "Write", "Grep"]tools: Read, Write, Grep
  2. Line 228: "Array of tool names" → "Comma-separated tool names"
  3. Line 230: tools: ["Read", "Write", "Grep", "Bash"]tools: Read, Write, Grep, Bash
  4. Lines 238-242: Updated all common tool set examples
  5. Line 441: Table format column updated

Checklist Verification


Recommendation: Approve and merge. This is exactly the kind of documentation fix that improves user experience by eliminating confusion between official docs and plugin examples.


@sjnims sjnims self-assigned this Dec 11, 2025
@claude claude Bot added documentation Improvements or additions to documentation component:skill Skills layer effort:small < 1 hour labels Dec 11, 2025
@sjnims sjnims merged commit 4ac66c4 into main Dec 11, 2025
8 checks passed
@sjnims sjnims deleted the docs/132-update-tools-field-format branch December 11, 2025 04:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component:skill Skills layer documentation Improvements or additions to documentation effort:small < 1 hour

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Docs]: Update tools field examples in agent-development skill to use comma-separated format

1 participant